home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / svgabg55 / mouse / hgxmouse.doc next >
Encoding:
Text File  |  1994-08-25  |  14.4 KB  |  435 lines
  1.  
  2.  
  3.                                 HGXMOUSE
  4.                      The Multi-Mode Mouse Cursor TSR
  5.                               Version 1.3
  6.  
  7.              Copyright (c) 1994 by Jordan Hargraphix Software
  8.                            All Rights Reserved
  9.  
  10.  
  11. =============================================================================
  12.  
  13.   The HGXMOUSE driver provides an enhanced interface for drawing the mouse
  14. cursor in modes the standard mouse drivers do not support.  It supports
  15. a wide range of SuperVGA cards and provides standard mouse cursor drawing 
  16. capabilities for 16, 256, 32k, 64k and TrueColor SuperVGA modes, 
  17. 16 and 256 color TweakedVGA modes, and tweaked and standard text modes.  
  18. It also provides the ability to set the cursor foreground and background 
  19. colors, and also the ability to use a bitmap for the mouse pointer.
  20. If your Svga card supports a hardware cursor, HGXMOUSE will use it to
  21. display the mouse cursor.
  22.  
  23.   Requirements:
  24.     An IBM PC AT or 100% compatible. (286 or better)
  25.     An EGA, VGA or SuperVGA video card.
  26.     A mouse driver (mouse.com or mouse.sys equivalent)
  27.  
  28.   Currently supported video cards:
  29.     VESA
  30.     Weitek
  31.     Chips & Technologies
  32.     Paradise (*)
  33.     Compaq
  34.     Video7
  35.     Genoa
  36.     Everex
  37.     Cirrus 54XX (*)
  38.     Cirrus 64XX
  39.     Trident 8800/8900
  40.     ATI
  41.     Ahead A & B
  42.     NCR
  43.     S3 (*)
  44.     Avance Logic 2101
  45.     MXIC 68000
  46.     Acumos
  47.     Realtek
  48.     Primus 2000
  49.     Oak
  50.     UMC
  51.     HMC
  52.     Tseng ET3000/ET4000/ET3000W32
  53.  
  54.     (*) Currently supports hardware cursor
  55.  
  56. =============================================================================
  57.  
  58.   Features of HGXMOUSE TSR:
  59.  
  60.     ------------------------------------------
  61.      Text mode graphical cursor driver
  62.  
  63.       * Normally, the mouse cursor in text mode is represented by a block
  64.       character, which can only be moved in character cell increments.
  65.       HGXMOUSE turns the block character into a graphical pointer (like
  66.       Norton Utilities and other programs) which can be moved in pixel
  67.       increments, but it will work with all existing applications that
  68.       use the software mouse cursor.
  69.  
  70.       * The default shape of the text mode graphical cursor can be changed 
  71.       with the standard mouse Set Pointer call (int 0x33, function 9).
  72.       The maximum size of the text mode cursor is 16x16.
  73.  
  74.     ------------------------------------------
  75.      Graphics mode cursor driver
  76.  
  77.       * The cursor shape can be changed in three ways:
  78.       a) Set Pointer mouse call (int 0x33, function 0x9).
  79.       b) Set Large Pointer call (int 0x33, function 0x12).
  80.          Maximum size of cursor is 32x32.
  81.       c) Set Bitmap Pointer call (int 0x33, function 0x4508)
  82.          This function allows you to use a bitmap for the mouse
  83.          pointer.  The maximum size of the cursor is 32x32.
  84.  
  85.       * Ability to set the cursor's foreground and background colors
  86.  
  87. =============================================================================
  88.  
  89.   Loading the HGXMOUSE TSR.
  90.  
  91.     The HGXMOUSE TSR is not a replacement for your mouse driver, but an
  92.   extension to it.  Therefore your mouse driver must be loaded before you
  93.   load HGXMOUSE.  Normal mouse functions will work when the HGXMOUSE driver
  94.   is loaded; the extended functions are not active until the driver is 
  95.   initialized.
  96.  
  97.   TSR Command-line options:
  98.  
  99.     The HGXMOUSE.EXE TSR supports several command-line options.
  100.  
  101.    /h, /? : Shows the available command line options.
  102.        /d : Detects and prints the Svga chipset, without installing the TSR.
  103.        /u : Uninstalls the TSR from memory.
  104.        /n : Disables the hardware cursor support.
  105.  
  106. =============================================================================
  107.   Registration fees
  108.  
  109.   HGXMOUSE alone                    $40
  110.   if ordered with one or more of my BGI drivers        $25
  111.  
  112. =============================================================================
  113.                   Appendix A
  114.  
  115.           Application Programming Interface
  116.  
  117.     HGXMOUSE provides extentions to the int 0x33 mouse programming API
  118. for initialization and de-initialization, cursor control and version
  119. information.
  120.  
  121.     A.1 ............................................ hgxInit
  122.     A.2 ............................................ hgxDeinit
  123.     A.3 ............................................ hgxBank
  124.     A.4 ............................................ hgxVersion
  125.     A.5 ............................................ hgxCursorFg
  126.     A.6 ............................................ hgxCursorBg
  127.     A.7 ............................................ hgxSetSacmap
  128.     A.8 ............................................ hgxSetBmpCursor
  129.  
  130. =============================================================================
  131.  
  132. 1) hgxInit: Enables the enhanced cursor drawing capabilities.
  133.  
  134.   hgxInit initializes HGXMOUSE with the current mode information.  This
  135. function must be called before any of the enhanced cursor drawing features
  136. can be used.  If you are using HGXMOUSE with my BGI drivers, you do not
  137. need to call this function, since the BGI drivers automatically initialize 
  138. HGXMOUSE during initgraph().
  139.  
  140.   Modes supported: All
  141.  
  142.   Input:
  143.     AX = 0x4500
  144.     SI = X resolution of mode (*)
  145.     DI = Y resolution of mode (*)
  146.     DX = Bytes per scanline
  147.     BL = Mode type
  148.      (0) MODE_P8        8-bit packed  (Mode 0x13 and SuperVGA 256 color)
  149.      (1) MODE_P15        15-bit packed (SuperVGA 32768 color)
  150.      (2) MODE_P16        16-bit packed (SuperVGA 65536 color)
  151.      (3) MODE_P24        24-bit packed (SuperVGA TrueColor)
  152.      (4) MODE_PL4        4-bit planar  (SuperVGA & TweakedVGA 16 color)
  153.      (5) MODE_PL8        8-bit planar  (Mode X & other tweaked 256-color)
  154.      (7) MODE_TWKTEXT    Tweaked text
  155.      (6) MODE_TEXT        Standard text mode
  156.  
  157.   Returns:
  158.     AL = 0x45 if successful
  159.     AH = error code (0 if successful)
  160.  
  161.  (*) Only needed for graphical modes, the text mode cursor determines the
  162.  current resolution from the number of rows and columns currently displayed.
  163.  
  164.  Example: To initialize the HGXMOUSE TSR for 320x200x256 mode 0x13
  165.  
  166.     int hgxInit() {
  167.       union REGS regs;
  168.  
  169.       regs.x.ax = 0x4500;
  170.       regs.x.si = 320;    // X resolution
  171.       regs.x.di = 200;    // Y resolution
  172.       regs.h.bl = 0;    // MODE_P8
  173.       regs.x.dx = 320;    // Bytes per line
  174.       int86(0x33, ®s, ®s);
  175.       return ((regs.h.al == 0x45) ? 1 : 0);
  176.     };
  177.  
  178. =============================================================================
  179.  
  180. 2) hgxDeInit: Disables the extended cursor drawing capabilities.
  181.  
  182.   hgxDeInit is the opposite of hgxInit.  It disables the enhanced features
  183. of the HGXMOUSE driver and returns the mouse operation to normal mode.
  184. Any call to hgxInit must be matched with a call to hgxDeInit.  Again, if
  185. you are using my BGI drivers with HGXMOUSE, they will automatically disable
  186. HGXMOUSE when closegraph() is called.
  187.  
  188.   Modes supported: All
  189.  
  190.   Input:
  191.     AX = 0x4501
  192.  
  193.   Output:
  194.     AL = 0x45 if successful
  195.     AH = error code (0 if successful)
  196.  
  197.  Example: To de-initialize the extended functions
  198.  
  199.     int hgxDeinit() {
  200.       union REGS regs;
  201.  
  202.       regs.x.ax = 0x4501;
  203.       int86(0x33, ®s, ®s);
  204.       return ((regs.h.al == 0x45) ? 1 : 0);
  205.     };
  206.  
  207. =============================================================================
  208.  
  209. 3) hgxBank: Sets the current SVGA bank for HGXMOUSE.
  210.  
  211.   hgxBank sets the current SuperVGA drawing bank.  Current SuperVGA cards
  212. have 1MB to 4MB onboard, but only 64KB can be accessed at one time.  A paging
  213. scheme is used to access the entire video memory in 64KB chunks.  If you
  214. are setting the bank directly, HGXMOUSE needs to keep updated with the
  215. current bank so that when it draws the cursor on the screen, it properly
  216. restores the current bank the application is using.  If you are using my
  217. BGI drivers, they automatically update the HGXMOUSE bank.
  218.  
  219.   Modes supported: All
  220.  
  221.   Input:
  222.     AX = 0x4504
  223.     DL = bank number
  224.  
  225.   Output:
  226.     AL = 0x45 if successful
  227.     AH = error code (0 if successful)
  228.  
  229. =============================================================================
  230.  
  231. 4) hgxVersion: Get version of HGXMOUSE
  232.  
  233.   hgxVersion returns the current version of the HGXMOUSE driver.
  234.  
  235.   Modes supported: All
  236.  
  237.   Input:
  238.     AX = 0x4504
  239.  
  240.   Output:
  241.     BH = Major version
  242.     BL = Minor version
  243.     CX = Code segment of TSR
  244.  
  245.   Example: To get the curent version of HGXMOUSE
  246.  
  247.     int hgxVersion(int *major, int *minor) {
  248.       union REGS regs;
  249.  
  250.       regs.x.ax = 0x4504;
  251.       int86(0x33, ®s, ®s);
  252.       if (major) *major = bh;
  253.       if (minor) *minor = bl;
  254.       return ((regs.h.al == 0x45) ? 1 : 0);
  255.     };
  256.  
  257. =============================================================================
  258.  
  259. 5) hgxCursorFG: Sets the cursor's current foreground color.
  260.  
  261.   hgxCursorFG allows you to set the current RGB foreground color of the cursor.
  262. The foreground color is the color that normally displays as white in the
  263. standard mouse cursor.
  264.  
  265.   Modes supported: MODE_P8, MODE_P15, MODE_P16, MODE_P24, MODE_PL8
  266.              (MODE_PL4 - 16 colors, currently not supported)
  267.  
  268.   Input:
  269.     AX = 0x4505
  270.     BL = Blue value for TrueColor & HiColor modes
  271.        = Color index (0-255) for 256 color modes
  272.        = Color index (0-15) for 16 color modes
  273.     BH = Green value for HiColor & TrueColor modes
  274.        = N/A for 16 & 256-color modes
  275.     CL = Red value for HiColor & TrueColor modes
  276.        = N/A for 16 & 256-color modes
  277.  
  278.   Output:
  279.     AL = 0x45 if successful
  280.     AH = error code (0 if successful)
  281.  
  282. Note: Some hardware cursors can accept 24-bit color values in 16 & 256
  283.     color modes.
  284.  
  285.   Example: Set the cursor FG color
  286.  
  287.     int hgxSetCursorFG(int r, int g, int b) {
  288.       union REGS regs;
  289.  
  290.       regs.x.ax = 0x4505;
  291.       regs.h.bl = b;
  292.       regs.h.bh = g;
  293.       regs.h.cl = r;
  294.       int86(0x33, ®s, ®s);
  295.       return ((regs.h.al == 0x45) ? 1 : 0);
  296.     };
  297.  
  298. =============================================================================
  299.  
  300. 6) hgxCursorBG: Sets the cursor's background color
  301.  
  302.   hgxCursorBG allows you to set the current RGB background color of the cursor.
  303. The background color is the color that normally displays as black in the
  304. standard mouse cursor.
  305.  
  306.   Modes supported: MODE_P8, MODE_P15, MODE_P16, MODE_P24, MODE_PL8
  307.              (MODE_PL4 - 16 colors, currently not supported)
  308.  
  309.   Input:
  310.     AX = 0x4506
  311.     BL = Blue value for TrueColor & HiColor modes
  312.        = Color index (0-255) for 256 color modes
  313.        = Color index (0-15) for 16 color modes
  314.     BH = Green value for HiColor & TrueColor modes
  315.        = N/A for 16 & 256-color modes
  316.     CL = Red value for HiColor & TrueColor modes
  317.        = N/A for 16 & 256-color modes
  318.  
  319.   Output:
  320.     AL = 0x45 if successful
  321.     AH = error code (0 if successful)
  322.  
  323. Note: Some hardware cursors can accept 24-bit color values in 16 & 256
  324.     color modes.
  325.  
  326.   Example: Set the cursor BG color
  327.  
  328.     int hgxSetCursorBG(int r, int g, int b) {
  329.       union REGS regs;
  330.  
  331.       regs.x.ax = 0x4506;
  332.       regs.h.bl = b;
  333.       regs.h.bh = g;
  334.       regs.h.cl = r;
  335.       int86(0x33, ®s, ®s);
  336.       return ((regs.h.al == 0x45) ? 1 : 0);
  337.     };
  338.  
  339. =============================================================================
  340.  
  341. 7) hgxSetSacmap: Sets the sacrifice character map for the text mode cursor.
  342.  
  343.   The text mode cursor works by copying the character definitions of the
  344.   characters under the cursor into a set of 'sacrifice' characters, then
  345.   drawing the bitmap of the cursor 'on top' of the bitmap in the sacrifice
  346.   characters.  This is why parts of the mouse cursor may appear on other
  347.   parts of the screen; those characters are part of the sacrifice map.
  348.   The sacrifice map can occupy up to 9 characters (3x3 grid) for a 16x16
  349.   cursor.
  350.  
  351.   In 25-line mode, the sacrifice characters should be taken from the range
  352.   0xC0-0xDF so that the 9th column will be duplicated, otherwise you may
  353.   see vertical lines running through the cursor as you move it around the
  354.   screen.
  355.  
  356.   Modes supported: MODE_TEXT
  357.  
  358.   Input:
  359.     AX = 0x4507
  360.     ES:BX = segment:offset of sacrifice character map (9 bytes)
  361.       Layout of sacrifice map
  362.       +---+---+---+
  363.       | 0 | 1 | 2 |
  364.       +---+---+---+
  365.       | 3 | 4 | 5 |
  366.       +---+---+---+
  367.       | 6 | 7 | 8 |
  368.       +---+---+---+
  369.  
  370.   Example: Set the current sacrifice character map
  371.  
  372.     int hgxSetSacmap(char sacChars[9]) {
  373.       union REGS regs;
  374.       struct SREGS sregs;
  375.  
  376.       regs.x.ax = 0x4507;
  377.       regs.x.bx = FP_OFF(sacChars);
  378.       sregs.es  = FP_SEG(sacChars);
  379.       int86x(0x33,®s,®s,&sregs);
  380.       return ((regs.h.al == 0x45) ? 1 : 0);
  381.     };
  382.  
  383. =============================================================================
  384.  
  385. 8) hgxBmpCursor: Sets bitmap data for the cursor pointer.
  386.  
  387.   hgxBmpCursor allows you to take any bitmap and use it as the mouse pointer.
  388.   The bitmap may contain pixels of any color, along with a special transparent
  389.   color.  Pixels of the transparent color will not be displayed when the
  390.   bitmap cursor is drawn to the screen.
  391.  
  392.   The format of the bitmap is mode-dependent, but it is the same format used
  393.   for each of my BGI drivers.
  394.  
  395.   Modes supported: MODE_P8, MODE_P15, MODE_P16, MODE_P24, MODE_PL8
  396.              (MODE_PL4 - 16 colors, currently not supported)
  397.  
  398.   Input:
  399.     AX=0x4508
  400.     BX=Horizontal hot spot of cursor
  401.     CX=Vertical hot spot of cursor
  402.     ES:DX = segment:offset of cursor data
  403.       Format of cursor data
  404.         offset    length
  405.         DX+0     4 bytes        Transparent color
  406.  
  407.         Format of transparent color: (x = don't care)
  408.         00000000RRRRRRRRGGGGGGGGBBBBBBBB - 24 bit modes
  409.         xxxxxxxxxxxxxxxxRRRRRGGGGGGBBBBB - 16 bit modes
  410.         xxxxxxxxxxxxxxxx0RRRRRGGGGGBBBBB - 15 bit modes
  411.         xxxxxxxxxxxxxxxxxxxxxxxxIIIIIIII - Color index for 256 colors
  412.  
  413.     ;; Following format is the same as the buffer used in getimage/putimage
  414.         DX+4    2 bytes        Width-1
  415.         DX+6    2 bytes        Height-1
  416.         DX+8    n bytes        image data
  417.  
  418.         Format of image data:
  419.         24 bit modes:      Each pixel is 4 bytes
  420.         16 & 15-bit modes: Each pixel is 2 bytes
  421.         256-color:         Each pixel is 1 byte
  422.  
  423. ;;*===============================*===========================================*
  424. ;;| Jordan Powell Hargrave        |   Internet: hargrave@dellgate.us.dell.com |
  425. ;;| 12310B Deer Falls Drive       |             jordanh@vern.bga.com          |
  426. ;;| Austin, TX 78729              |    CC mail: jordan_hargrave@dell.com      |
  427. ;;| (512) 219-6645                | Compuserve: [72510,1143]                  |
  428. ;;*===============================*===========================================*
  429. ;;| Mailing address:              | Please use the mailing address for all    |
  430. ;;|   8760-A Research Blvd, #256  | BGI-related correspondence.               |
  431. ;;|   Austin, TX 78758            |                                           |
  432. ;;|      (800) 219-6988           | Note for FAX: Please include my mailing   |
  433. ;;| FAX: (512) 458-6461           |    address and name in the header page.   |
  434. ;;================================*===========================================*
  435.